Bulk Import by Prompt

Introduction

The Assetic REST API's allow automation of data exchange importing (Data-Exchange-Integration), and document importing (Uploading-Files).

To simplify these upload processes, the Assetic Python SDK provides a tool that supports:

Upload one or more documents against an Assetic record such as an Asset or Functional Location. The tool uses a Microsoft Excel file to define the location of each document including it's relevant details and associations.
There are 2 options for bulk document upload:
1. Bulk import documents. The document may or may not also be flagged as a key photo.
2. Bulk import key photos. In this instance the document must be an image file and it will be loaded as the key photo for the asset
Initiate one or more Data Exchange imports using a Microsoft Excel file to define the location of each 'csv' import file and the import Profile Id

First ensure you have installed the Assetic Python SDK as per the article Assetic-Python-SDK-Quick-Start.

Prepare the tool - Python Script

Download the python script Assetic.BulkUploadPrompter.py or copy the following code into Notepad or another text or python editor.

import assetic
##Define the location of the assetic.ini file, or leave as None to use the
##default locations
inifile =  None
##Define the location of the log file, or leave as None for logging to screen
logfile =  None
##Define the loglevel - usually one of "Info","Debug","Error"
loglevel =  "Info"
  
asseticsdk = assetic.AsseticSDK(inifile,logfile,loglevel)
uploadapi = assetic.BulkProcesses()
uploadapi.bulk_upload_prompter()

Edit the default settings for the assetic.ini file, the log file and loglevel if neccessary.

This article will assume the script is saved as Assetic.BulkUploadPrompter.py

Note: Ensure the Excel document is closed prior to running the import because the import will need to update the document with the results.

Using the tool

Run the script Assetic.BulkUploadPrompter.py.
You will be prompted to enter a number corresponding to a list of options
1. Bulk Upload Documents
2. Data Exchange Upload using saved profile id
3. Data Exchange Upload Status Check
4. Exit
Enter one of the options. You will be prompted for further information as outlined in the sections below

Bulk Upload Documents

This will upload documents against assets.

If the document is a photo it may also be specified as the key photo for that asset.

Prompts

You will be prompted to enter the filename including file path of the Excel configuration file. The import will proceed if the Excel configuration file is found. The Excel configuration file is updated with the results of the import, so it needs to be closed. If the file is not found you will be prompted to re-enter the file name and path.
You will be prompted to enter "U" or "L" to indicate whether the documents will be uploaded to Assetic (U=upload), or whether to create document links (L=link). The default is "U", so unless you want to create links you can just hit enter. This setting will apply to all documents in the Excel configuration file.
You will be presented with a list of Assetic record types such as Asset, Functional Location, Work Request. Each type will have a number against it. When prompted enter the number that corresponds to record type you are loading documents against.
You will be presented with a list of Document Groups and prompted to enter the number that corresponds with the group name. Alternatively hit enter without entering a number and defaults will be used. For image files the default will be "Photos", otherwise the default is "Documents". The chosen Document Group will apply to all documents in the Excel. configuration file.
You will be presented with a list of Document Categories and prompted to enter the number that corresponds with the Document Category name. There is no default, but this field is not mandatory, so unless you want to set the Document Category you can just hit enter. This setting will apply to all documents in the Excel configuration.
If you chose a Document Category you will be presented with a list of Document Sub Categories and prompted to enter the number that corresponds with the Document Sub Category name. There is no default, but this field is not mandatory, so unless you want to set the Document Category you can just hit enter. This setting will apply to all documents in the Excel configuration.

The import will then proceed.

Excel configuration file - documents

Download the sample Excel template or create an Excel file (a XLSX/XLSM/XLTX/XLTM file) with the following columns:

Column Header	Description	Required
Id	User Friendly ID of the record that you are uploading the document against. The Id must exit in the selected record type. For example, if loading a document against an asset, then use the Asset Id	Yes
Document/Photos Complete File Path	The file name and the path to the file	Yes
Is Key Photo (TRUE/FALSE)	Boolean TRUE or FALSE	Yes
External Id	External reference Id. Maximum 200 characters	No
Label	A label to apply to a URL link. If not uploading links then it is optional	Conditional
Description	A description of the document	No

Note: It is the column order and not the column headers that are important. You can use any label for the column headers.

For each document add a new row and fill in the first 6 columns. Do not fill in any other columns as they will be overwritten by the import tool. The import tool will add 3 additional columns to track the success or otherwise of the import

Results of Import

Once the import has run, open the Excel document and check the results. Three additional columns as listed below will have been added to the Excel document.

Column Header	Description	Required
Migrated Document Id	The Assetic unique document Id for the uploaded document	Populated by integration
Operation Performed On	The date and time the document was uploaded	Populated by integration
Status	If "SUCCESS" then the document was uploaded, otherwise an error message is presented	Populated by integration

Data Exchange Upload using profile Id

This will use Data Exchange to create/update records in Assetic. Refer to the Data Exchange article Data Exchange for further details about data exchange. This import capability is not limited to assets.

Note that Data Exchange may queue uploads depending on how many other users are performing bulk tasks. For this reason the import process is a 2-step process:

Initiate the Data Exchange import job by uploading the csv file and creating a job for the uploaded file and Data Exchange import profile.
Check the status of the Data Exchange import job to see if the task has been processed

If you have chosen option 2 in Assetic.BulkUploadPrompter.py (initiate the import job) then you will be prompted to enter the filename including file path of the Excel configuration file. The import will proceed if the Excel configuration file is found. The Excel configuration file is updated with the results of the import.

If you have chosen option 3 in Assetic.BulkUploadPrompter.py then you will be prompted to enter:

The filename including file path of the Excel configuration file. The Excel file will contain the Data Exchange job Id which can be used to check the status of the import job and update the Excel file with the current status.
The folder to save the Data Exchange error file (if one is generated). If a folder is not supplied, the same folder as the Excel configuration file is used.

You may also view the status of a Data Exchange job via the Assetic browser application itself by opening the Data Exchange Import History page.

Excel configuration file - Data Exchange

Download the sample Excel template or Create an Excel file (a XLSX/XLSM/XLTX/XLTM file) with the following columns:

[caption]
Column Header	Description	Required
Data-exchange Profile Id	The Id of the pre-saved data exchange import profile. Refer to article Data-Exchange-Integration to get this Id	Yes
Document to Import (Complete file-path)	The file name and the path to the csv import file	Yes

Note: It is the column order and not the column headers that are important. You can use any label for the column headers.

For each Data Exchange import csv file, add a new row to the Excel configuration file and fill in the first 2 columns. Do not fill in any other columns as they will be overwritten by the import tool. The import tool will add additional columns to track the success (or otherwise) of the import.

Results of Data Exchange job creation

Once the process to create the Data Exchange jobs has run, open the Excel configuration file and check the results. Additional columns as listed below will have been added to the Excel configuration file (if not already present).

Column Header	Description	Required
Imported Document Id	The Assetic unique document Id for the uploaded csv document containing the data to import	Populated by integration
Data-exchange Job Id	The Assetic unique Data Exchange job Id	Populated by integration
Operation Performed On	The date and time that the job was created by this tool	Populated by integration
Status	This indicates whether the Data Exchange job creation was successful.	Populated by integration

Note that if you are re-using an Excel configuration file from a previous import there is no need to remove these additional fields from the file, they will be overwritten by the process when it runs. It would however be best to remove the old results (keeping the headers) so that there is no confusion as the the currency of the results once the process is run.

Results of Data Exchange job status check

One the process to check the status of the Data Exchange jobs has run, open the Excel configuration file and check the results. Additional columns as listed below will have been added to the Excel configuration file (if not already present).

Column Header	Description	Required
Error Document Id	If there were Data Exchange errors when the job was processed an error file will have been created. This is the Assetic unique document Id for the error file.	Populated by integration
Summary	A summary of the status check which may be "SUCCESS" or an error message. This is the same summary as is presented in the Assetic application itself if checking job status	Populated by integration

An error file may be generated by Data Exchange. If one is generated it is downloaded to the nominated folder. The name of the error file is a concatenation of the name of original csv file used for the import, and the "Error Document Id".